home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1998 November / Freeware November 1998.img / dist / fw_tar.idb / usr / freeware / info / tar.info-4.z / tar.info-4 (.txt)
GNU Info File  |  1998-05-21  |  51KB  |  886 lines
  1. This is Info file tar.info, produced by Makeinfo version 1.67 from the
  2. input file tar.texi.
  3. START-INFO-DIR-ENTRY
  4. * tar: (tar).            Making tape (or disk) archives.
  5. END-INFO-DIR-ENTRY
  6.    This file documents GNU `tar', a utility used to store, backup, and
  7. transport files.
  8.    Copyright (C) 1992, 1994, 1995, 1996, 1997 Free Software Foundation,
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Foundation.
  20.    This file documents GNU `tar', which is a utility used to store,
  21. backup, and transport files.  `tar' is a tape (or disk) archiver.  This
  22. manual documents the release 1.12.
  23. File: tar.info,  Node: Full Dumps,  Next: Inc Dumps,  Prev: Backups,  Up: Backups
  24. Using `tar' to Perform Full Dumps
  25. =================================
  26.      *(This message will disappear, once this node revised.)*
  27.    Full dumps should only be made when no other people or programs are
  28. modifying files in the filesystem.  If files are modified while `tar'
  29. is making the backup, they may not be stored properly in the archive,
  30. in which case you won't be able to restore them if you have to.  (Files
  31. not being modified are written with no trouble, and do not corrupt the
  32. entire archive.)
  33.    You will want to use the `--label=ARCHIVE-LABEL' (`-V
  34. ARCHIVE-LABEL') option to give the archive a volume label, so you can
  35. tell what this archive is even if the label falls off the tape, or
  36. anything like that.
  37.    Unless the filesystem you are dumping is guaranteed to fit on one
  38. volume, you will need to use the `--multi-volume' (`-M') option.  Make
  39. sure you have enough tapes on hand to complete the backup.
  40.    If you want to dump each filesystem separately you will need to use
  41. the `--one-file-system' (`-l') option to prevent `tar' from crossing
  42. filesystem boundaries when storing (sub)directories.
  43.    The `--incremental' (`-G') option is not needed, since this is a
  44. complete copy of everything in the filesystem, and a full restore from
  45. this backup would only be done onto a completely empty disk.
  46.    Unless you are in a hurry, and trust the `tar' program (and your
  47. tapes), it is a good idea to use the `--verify' (`-W') option, to make
  48. sure your files really made it onto the dump properly.  This will also
  49. detect cases where the file was modified while (or just after) it was
  50. being archived.  Not all media (notably cartridge tapes) are capable of
  51. being verified, unfortunately.
  52.    `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') take a
  53. file name argument always.  If the file doesn't exist, run a level zero
  54. dump, creating the file.  If the file exists, uses that file to see
  55. what has changed.
  56.    `--incremental' (`-G')
  57.    `--incremental' (`-G') handle old GNU-format incremental backup.
  58.    This option should only be used when creating an incremental backup
  59. of a filesystem.  When the `--incremental' (`-G') option is used, `tar'
  60. writes, at the beginning of the archive, an entry for each of the
  61. directories that will be operated on.  The entry for a directory
  62. includes a list of all the files in the directory at the time the dump
  63. was done, and a flag for each file indicating whether the file is going
  64. to be put in the archive.  This information is used when doing a
  65. complete incremental restore.
  66.    Note that this option causes `tar' to create a non-standard archive
  67. that may not be readable by non-GNU versions of the `tar' program.
  68.    The `--incremental' (`-G') option means the archive is an incremental
  69. backup.  Its meaning depends on the command that it modifies.
  70.    If the `--incremental' (`-G') option is used with `--list' (`-t'),
  71. `tar' will list, for each directory in the archive, the list of files in
  72. that directory at the time the archive was created.  This information
  73. is put out in a format that is not easy for humans to read, but which
  74. is unambiguous for a program: each file name is preceded by either a
  75. `Y' if the file is present in the archive, an `N' if the file is not
  76. included in the archive, or a `D' if the file is a directory (and is
  77. included in the archive).  Each file name is terminated by a null
  78. character.  The last file is followed by an additional null and a
  79. newline to indicate the end of the data.
  80.    If the `--incremental' (`-G') option is used with `--extract'
  81. (`--get', `-x'), then when the entry for a directory is found, all
  82. files that currently exist in that directory but are not listed in the
  83. archive *are deleted from the directory*.
  84.    This behavior is convenient when you are restoring a damaged file
  85. system from a succession of incremental backups: it restores the entire
  86. state of the file system to that which obtained when the backup was
  87. made.  If you don't use `--incremental' (`-G'), the file system will
  88. probably fill up with files that shouldn't exist any more.
  89.    `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') handle new
  90. GNU-format incremental backup.  This option handles new GNU-format
  91. incremental backup.  It has much the same effect as `--incremental'
  92. (`-G'), but also the time when the dump is done and the list of
  93. directories dumped is written to the given FILE. When restoring, only
  94. files newer than the saved time are restored, and the direcotyr list is
  95. used to speed up operations.
  96.    `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') acts like
  97. `--incremental' (`-G'), but when used in conjunction with `--create'
  98. (`-c') will also cause `tar' to use the file FILE, which contains
  99. information about the state of the filesystem at the time of the last
  100. backup, to decide which files to include in the archive being created.
  101. That file will then be updated by `tar'.  If the file FILE does not
  102. exist when this option is specified, `tar' will create it, and include
  103. all appropriate files in the archive.
  104.    The file, which is archive independent, contains the date it was last
  105. modified and a list of devices, inode numbers and directory names.
  106. `tar' will archive files with newer mod dates or inode change times,
  107. and directories with an unchanged inode number and device but a changed
  108. directory name.  The file is updated after the files to be archived are
  109. determined, but before the new archive is actually created.
  110.    GNU `tar' actually writes the file twice: once before the data and
  111. written, and once after.
  112. File: tar.info,  Node: Inc Dumps,  Next: incremental and listed-incremental,  Prev: Full Dumps,  Up: Backups
  113. Using `tar' to Perform Incremental Dumps
  114. ========================================
  115.      *(This message will disappear, once this node revised.)*
  116.    Performing incremental dumps is similar to performing full dumps,
  117. although a few more options will usually be needed.
  118.    You will need to use the `-N DATE' option to tell `tar' to only
  119. store files that have been modified since DATE.  DATE should be the
  120. date and time of the last full/incremental dump.
  121.    A standard scheme is to do a *monthly* (full) dump once a month, a
  122. *weekly* dump once a week of everything since the last monthly and a
  123. *daily* every day of everything since the last (weekly or monthly) dump.
  124.    Here is a copy of the script used to dump the filesystems of the
  125. machines here at the Free Software Foundation.  This script is run via
  126. `cron' late at night when people are least likely to be using the
  127. machines.  This script dumps several filesystems from several machines
  128. at once (via NFS).  The operator is responsible for ensuring that all
  129. the machines will be up at the time the dump happens.  If a machine is
  130. not running, its files will not be dumped, and the next day's
  131. incremental dump will *not* store files that would have gone onto that
  132. dump.
  133.      #!/bin/csh
  134.      # Dump thingie
  135.      set now = `date`
  136.      set then = `cat date.nfs.dump`
  137.      /u/hack/bin/tar -c -G -v\
  138.       -f /dev/rtu20\
  139.       -b 126\
  140.       -N "$then"\
  141.       -V "Dump from $then to $now"\
  142.       /alpha-bits/gp\
  143.       /gnu/hack\
  144.       /hobbes/u\
  145.       /spiff/u\
  146.       /sugar-bombs/u
  147.      echo $now > date.nfs.dump
  148.      mt -f /dev/rtu20 rew
  149.    Output from this script is stored in a file, for the operator to
  150. read later.
  151.    This script uses the file `date.nfs.dump' to store the date/time of
  152. the last dump.
  153.    Since this is a streaming tape drive, no attempt to verify the
  154. archive is done.  This is also why the high blocking factor (126) is
  155. used.  The tape drive must also be rewound by the `mt' command after
  156. the dump is made.
  157. File: tar.info,  Node: incremental and listed-incremental,  Next: Backup Levels,  Prev: Inc Dumps,  Up: Backups
  158. The Incremental Options
  159. =======================
  160.      *(This message will disappear, once this node revised.)*
  161.    `--incremental' (`-G') is used in conjunction with `--create' (`-c'),
  162. `--extract' (`--get', `-x') or `--list' (`-t') when backing up and
  163. restoring file systems.  An archive cannot be extracted or listed with
  164. the `--incremental' (`-G') option specified unless it was created with
  165. the option specified.  This option should only be used by a script, not
  166. by the user, and is usually disregarded in favor of
  167. `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE'), which is
  168. described below.
  169.    `--incremental' (`-G') in conjunction with `--create' (`-c') causes
  170. `tar' to write, at the beginning of the archive, an entry for each of
  171. the directories that will be archived.  The entry for a directory
  172. includes a list of all the files in the directory at the time the
  173. archive was created and a flag for each file indicating whether or not
  174. the file is going to be put in the archive.
  175.    Note that this option causes `tar' to create a non-standard archive
  176. that may not be readable by non-GNU versions of the `tar' program.
  177.    `--incremental' (`-G') in conjunction with `--extract' (`--get',
  178. `-x') causes `tar' to read the lists of directory contents previously
  179. stored in the archive, *delete* files in the file system that did not
  180. exist in their directories when the archive was created, and then
  181. extract the files in the archive.
  182.    This behavior is convenient when restoring a damaged file system from
  183. a succession of incremental backups: it restores the entire state of
  184. the file system to that which obtained when the backup was made.  If
  185. `--incremental' (`-G') isn't specified, the file system will probably
  186. fill up with files that shouldn't exist any more.
  187.    `--incremental' (`-G') in conjunction with `--list' (`-t'), causes
  188. `tar' to print, for each directory in the archive, the list of files in
  189. that directory at the time the archive was created.  This information
  190. is put out in a format that is not easy for humans to read, but which
  191. is unambiguous for a program: each file name is preceded by either a
  192. `Y' if the file is present in the archive, an `N' if the file is not
  193. included in the archive, or a `D' if the file is a directory (and is
  194. included in the archive).  Each file name is terminated by a null
  195. character.  The last file is followed by an additional null and a
  196. newline to indicate the end of the data.
  197.    `--listed-incremental=SNAPSHOT-FILE' (`-g SNAPSHOT-FILE') acts like
  198. `--incremental' (`-G'), but when used in conjunction with `--create'
  199. (`-c') will also cause `tar' to use the file SNAPSHOT-FILE, which
  200. contains information about the state of the file system at the time of
  201. the last backup, to decide which files to include in the archive being
  202. created.  That file will then be updated by `tar'.  If the file FILE
  203. does not exist when this option is specified, `tar' will create it, and
  204. include all appropriate files in the archive.
  205.    The file FILE, which is archive independent, contains the date it
  206. was last modified and a list of devices, inode numbers and directory
  207. names.  `tar' will archive files with newer mod dates or inode change
  208. times, and directories with an unchanged inode number and device but a
  209. changed directory name.  The file is updated after the files to be
  210. archived are determined, but before the new archive is actually created.
  211.    Despite it should be obvious that a device has a non-volatile value,
  212. NFS devices have non-dependable values when an automounter gets in the
  213. picture.  This led to a great deal of spurious redumping in incremental
  214. dumps, so it is somewhat useless to compare two NFS devices numbers
  215. over time.  So `tar' now considers all NFS devices as being equal when
  216. it comes to comparing directories; this is fairly gross, but there does
  217. not seem to be a better way to go.
  218. File: tar.info,  Node: Backup Levels,  Next: Backup Parameters,  Prev: incremental and listed-incremental,  Up: Backups
  219. Levels of Backups
  220. =================
  221.      *(This message will disappear, once this node revised.)*
  222.    An archive containing all the files in the file system is called a
  223. "full backup" or "full dump".  You could insure your data by creating a
  224. full dump every day.  This strategy, however, would waste a substantial
  225. amount of archive media and user time, as unchanged files are daily
  226. re-archived.
  227.    It is more efficient to do a full dump only occasionally.  To back up
  228. files between full dumps, you can a incremental dump.  A "level one"
  229. dump archives all the files that have changed since the last full dump.
  230.    A typical dump strategy would be to perform a full dump once a week,
  231. and a level one dump once a day.  This means some versions of files
  232. will in fact be archived more than once, but this dump strategy makes
  233. it possible to restore a file system to within one day of accuracy by
  234. only extracting two archives--the last weekly (full) dump and the last
  235. daily (level one) dump.  The only information lost would be in files
  236. changed or created since the last daily backup.  (Doing dumps more than
  237. once a day is usually not worth the trouble).
  238.    GNU `tar' comes with scripts you can use to do full and level-one
  239. dumps.  Using scripts (shell programs) to perform backups and
  240. restoration is a convenient and reliable alternative to typing out file
  241. name lists and `tar' commands by hand.
  242.    Before you use these scripts, you need to edit the file
  243. `backup-specs', which specifies parameters used by the backup scripts
  244. and by the restore script.  .  .  Once the backup parameters are set,
  245. you can perform backups or restoration by running the appropriate
  246. script.
  247.    The name of the restore script is `restore'.  .  The names of the
  248. level one and full backup scripts are, respectively, `level-1' and
  249. `level-0'.  The `level-0' script also exists under the name `weekly',
  250. and the `level-1' under the name `daily'--these additional names can be
  251. changed according to your backup schedule.  , for more information on
  252. running the restoration script.  , for more information on running the
  253. backup scripts.
  254.    *Please Note:* The backup scripts and the restoration scripts are
  255. designed to be used together.  While it is possible to restore files by
  256. hand from an archive which was created using a backup script, and to
  257. create an archive by hand which could then be extracted using the
  258. restore script, it is easier to use the scripts.  .  *Note Inc Dumps::,
  259. and *Note Inc Dumps::, before making such an attempt.
  260. File: tar.info,  Node: Backup Parameters,  Next: Scripted Backups,  Prev: Backup Levels,  Up: Backups
  261. Setting Parameters for Backups and Restoration
  262. ==============================================
  263.      *(This message will disappear, once this node revised.)*
  264.    The file `backup-specs' specifies backup parameters for the backup
  265. and restoration scripts provided with `tar'.  You must edit
  266. `backup-specs' to fit your system configuration and schedule before
  267. using these scripts.
  268.    , for an explanation of this syntax.
  269. `ADMINISTRATOR'
  270.      The user name of the backup administrator.
  271. `BACKUP_HOUR'
  272.      The hour at which the backups are done.  This can be a number from
  273.      0 to 23, or the string `now'.
  274. `TAPE_FILE'
  275.      The device `tar' writes the archive to.  This device should be
  276.      attached to the host on which the dump scripts are run.
  277. `TAPE_STATUS'
  278.      The command to use to obtain the status of the archive device,
  279.      including error count.  On some tape drives there may not be such a
  280.      command; in that case, simply use `TAPE_STATUS=false'.
  281. `BLOCKING'
  282.      The blocking factor `tar' will use when writing the dump archive.
  283.      *Note Blocking Factor::.
  284. `BACKUP_DIRS'
  285.      A list of file systems to be dumped.  You can include any directory
  286.      name in the list--subdirectories on that file system will be
  287.      included, regardless of how they may look to other networked
  288.      machines.  Subdirectories on other file systems will be ignored.
  289.      The host name specifies which host to run `tar' on, and should
  290.      normally be the host that actually contains the file system.
  291.      However, the host machine must have GNU `tar' installed, and must
  292.      be able to access the directory containing the backup scripts and
  293.      their support files using the same file name that is used on the
  294.      machine where the scripts are run (ie. what `pwd' will print when
  295.      in that directory on that machine).  If the host that contains the
  296.      file system does not have this capability, you can specify another
  297.      host as long as it can access the file system through NFS.
  298. `BACKUP_FILES'
  299.      A list of individual files to be dumped.  These should be
  300.      accessible from the machine on which the backup script is run.
  301. * Menu:
  302. * backup-specs example::        An Example Text of `Backup-specs'
  303. * Script Syntax::               Syntax for `Backup-specs'
  304. File: tar.info,  Node: backup-specs example,  Next: Script Syntax,  Prev: Backup Parameters,  Up: Backup Parameters
  305. An Example Text of `Backup-specs'
  306. ---------------------------------
  307.      *(This message will disappear, once this node revised.)*
  308.    The following is the text of `backup-specs' as it appears at FSF:
  309.      # site-specific parameters for file system backup.
  310.      
  311.      ADMINISTRATOR=friedman
  312.      BACKUP_HOUR=1
  313.      TAPE_FILE=/dev/nrsmt0
  314.      TAPE_STATUS="mts -t $TAPE_FILE"
  315.      BLOCKING=124
  316.      BACKUP_DIRS="
  317.          albert:/fs/fsf
  318.          apple-gunkies:/gd
  319.          albert:/fs/gd2
  320.          albert:/fs/gp
  321.          geech:/usr/jla
  322.          churchy:/usr/roland
  323.          albert:/
  324.          albert:/usr
  325.          apple-gunkies:/
  326.          apple-gunkies:/usr
  327.          gnu:/hack
  328.          gnu:/u
  329.          apple-gunkies:/com/mailer/gnu
  330.          apple-gunkies:/com/archive/gnu"
  331.      
  332.      BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
  333. File: tar.info,  Node: Script Syntax,  Prev: backup-specs example,  Up: Backup Parameters
  334. Syntax for `Backup-specs'
  335. -------------------------
  336.      *(This message will disappear, once this node revised.)*
  337.    `backup-specs' is in shell script syntax.  The following conventions
  338. should be considered when editing the script:
  339.    A quoted string is considered to be contiguous, even if it is on more
  340. than one line.  Therefore, you cannot include commented-out lines
  341. within a multi-line quoted string.  BACKUP_FILES and BACKUP_DIRS are
  342. the two most likely parameters to be multi-line.
  343.    A quoted string typically cannot contain wildcards.  In
  344. `backup-specs', however, the parameters BACKUP_DIRS and BACKUP_FILES
  345. can contain wildcards.
  346. File: tar.info,  Node: Scripted Backups,  Next: Scripted Restoration,  Prev: Backup Parameters,  Up: Backups
  347. Using the Backup Scripts
  348. ========================
  349.      *(This message will disappear, once this node revised.)*
  350.    The syntax for running a backup script is:
  351.      `script-name' [TIME-TO-BE-RUN]
  352.    where TIME-TO-BE-RUN can be a specific system time, or can be `now'.
  353. If you do not specify a time, the script runs at the time specified in
  354. `backup-specs' ().
  355.    You should start a script with a tape or disk mounted.  Once you
  356. start a script, it prompts you for new tapes or disks as it needs them.
  357. Media volumes don't have to correspond to archive files--a
  358. multi-volume archive can be started in the middle of a tape that
  359. already contains the end of another multi-volume archive.  The
  360. `restore' script prompts for media by its archive volume, so to avoid
  361. an error message you should keep track of which tape (or disk) contains
  362. which volume of the archive.  .  .
  363.    The backup scripts write two files on the file system.  The first is
  364. a record file in `/etc/tar-backup/', which is used by the scripts to
  365. store and retrieve information about which files were dumped.  This
  366. file is not meant to be read by humans, and should not be deleted by
  367. them.  , for a more detailed explanation of this file.
  368.    The second file is a log file containing the names of the file
  369. systems and files dumped, what time the backup was made, and any error
  370. messages that were generated, as well as how much space was left in the
  371. media volume after the last volume of the archive was written.  You
  372. should check this log file after every backup.  The file name is
  373. `log-MMM-DDD-YYYY-level-1' or `log-MMM-DDD-YYYY-full'.
  374.    The script also prints the name of each system being dumped to the
  375. standard output.
  376. File: tar.info,  Node: Scripted Restoration,  Prev: Scripted Backups,  Up: Backups
  377. Using the Restore Script
  378. ========================
  379.      *(This message will disappear, once this node revised.)*
  380.      *Warning:* The GNU `tar' distribution does *not* provide any such
  381.      `restore' script yet.  This section is only listed here for
  382.      documentation maintenance purposes.  In any case, all contents is
  383.      subject to change as things develop.
  384.    To restore files that were archived using a scripted backup, use the
  385. `restore' script.  The syntax for the script is:
  386.    where ***** are the file systems to restore from, and ***** is a
  387. regular expression which specifies which files to restore.  If you
  388. specify -all, the script restores all the files in the file system.
  389.    You should start the restore script with the media containing the
  390. first volume of the archive mounted.  The script will prompt for other
  391. volumes as they are needed.  If the archive is on tape, you don't need
  392. to rewind the tape to to its beginning--if the tape head is positioned
  393. past the beginning of the archive, the script will rewind the tape as
  394. needed.  , for a discussion of tape positioning.
  395.    If you specify `--all' as the FILES argument, the `restore' script
  396. extracts all the files in the archived file system into the active file
  397. system.
  398.      *Warning:* The script will delete files from the active file
  399.      system if they were not in the file system when the archive was
  400.      made.
  401.    *Note Inc Dumps::, and *Note Inc Dumps::, for an explanation of how
  402. the script makes that determination.
  403. File: tar.info,  Node: Choosing,  Next: Date input formats,  Prev: Backups,  Up: Top
  404. Choosing Files and Names for `tar'
  405. **********************************
  406.      *(This message will disappear, once this node revised.)*
  407.    Certain options to `tar' enable you to specify a name for your
  408. archive.  Other options let you decide which files to include or exclude
  409. from the archive, based on when or whether files were modified, whether
  410. the file names do or don't match specified patterns, or whether files
  411. are in specified directories.
  412. * Menu:
  413. * file::                        Choosing the Archive's Name
  414. * Selecting Archive Members::
  415. * files::                       Reading Names from a File
  416. * exclude::                     Excluding Some Files
  417. * Wildcards::
  418. * after::                       Operating Only on New Files
  419. * recurse::                     Descending into Directories
  420. * one::                         Crossing Filesystem Boundaries
  421. File: tar.info,  Node: file,  Next: Selecting Archive Members,  Prev: Choosing,  Up: Choosing
  422. Choosing and Naming Archive Files
  423. =================================
  424.      *(This message will disappear, once this node revised.)*
  425.    By default, `tar' uses an archive file name that was compiled when
  426. it was built on the system; usually this name refers to some physical
  427. tape drive on the machine.  However, the person who installed `tar' on
  428. the system may not set the default to a meaningful value as far as most
  429. users are concerned.  As a result, you will usually want to tell `tar'
  430. where to find (or create) the archive.  The `--file=ARCHIVE-NAME' (`-f
  431. ARCHIVE-NAME') option allows you to either specify or name a file to
  432. use as the archive instead of the default archive file location.
  433. `--file=ARCHIVE-NAME'
  434. `-f ARCHIVE-NAME'
  435.      Name the archive to create or operate on.  Use in conjunction with
  436.      any operation.
  437.    For example, in this `tar' command,
  438.      $ tar -cvf collection.tar blues folk jazz
  439. `collection.tar' is the name of the archive.  It must directly follow
  440. the `-f' option, since whatever directly follows `-f' *will* end up
  441. naming the archive.  If you neglect to specify an archive name, you may
  442. end up overwriting a file in the working directory with the archive you
  443. create since `tar' will use this file's name for the archive name.
  444.    An archive can be saved as a file in the file system, sent through a
  445. pipe or over a network, or written to an I/O device such as a tape,
  446. floppy disk, or CD write drive.
  447.    If you do not name the archive, `tar' uses the value of the
  448. environment variable `TAPE' as the file name for the archive.  If that
  449. is not available, `tar' uses a default, compiled-in archive name,
  450. usually that for tape unit zero (ie. `/dev/tu00').  `tar' always needs
  451. an archive name.
  452.    If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from
  453. standard input (when listing or extracting files), or writes it to
  454. standard output (when creating an archive).  If you use `-' as an
  455. ARCHIVE-NAME when modifying an archive, `tar' reads the original
  456. archive from its standard input and writes the entire new archive to
  457. its standard output.
  458.      $ cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)
  459.    To specify an archive file on a device attached to a remote machine,
  460. use the following:
  461.      --file=HOSTNAME:/DEV/FILE NAME
  462. `tar' will complete the remote connection, if possible, and prompt you
  463. for a username and password.  If you use `--file=@HOSTNAME:/DEV/FILE
  464. NAME', `tar' will complete the remote connection, if possible, using
  465. your username as the username on the remote machine.
  466.    If the archive file name includes a colon (`:'), then it is assumed
  467. to be a file on another machine.  If the archive file is
  468. `USER@HOST:FILE', then FILE is used on the host HOST.  The remote host
  469. is accessed using the `rsh' program, with a username of USER.  If the
  470. username is omitted (along with the `@' sign), then your user name will
  471. be used.  (This is the normal `rsh' behavior.)  It is necessary for the
  472. remote machine, in addition to permitting your `rsh' access, to have
  473. the `/usr/ucb/rmt' program installed.  If you need to use a file whose
  474. name includes a colon, then the remote tape drive behavior can be
  475. inhibited by using the `--force-local' option.
  476.    When the archive is being created to `/dev/null', GNU `tar' tries to
  477. minimize input and output operations.  The Amanda backup system, when
  478. used with GNU `tar', has an initial sizing pass which uses this feature.
  479. File: tar.info,  Node: Selecting Archive Members,  Next: files,  Prev: file,  Up: Choosing
  480. Selecting Archive Members
  481. =========================
  482.    "File Name arguments" specify which files in the file system `tar'
  483. operates on, when creating or adding to an archive, or which archive
  484. members `tar' operates on, when reading or deleting from an archive.
  485. *Note Operations::.
  486.    To specify file names, you can include them as the last arguments on
  487. the command line, as follows:
  488.      tar OPERATION [OPTION1 OPTION2 ...] [FILE NAME-1 FILE NAME-2 ...]
  489.    If you specify a directory name as a file name argument, all the
  490. files in that directory are operated on by `tar'.
  491.    If you do not specify files when `tar' is invoked with `--create'
  492. (`-c'), `tar' operates on all the non-directory files in the working
  493. directory.  If you specify either `--list' (`-t') or `--extract'
  494. (`--get', `-x'), `tar' operates on all the archive members in the
  495. archive.  If you specify any operation other than one of these three,
  496. `tar' does nothing.
  497.    By default, `tar' takes file names from the command line.  However,
  498. there are other ways to specify file or member names, or to modify the
  499. manner in which `tar' selects the files or members upon which to
  500. operate; .  In general, these methods work both for specifying the
  501. names of files and archive members.
  502. File: tar.info,  Node: files,  Next: exclude,  Prev: Selecting Archive Members,  Up: Choosing
  503. Reading Names from a File
  504. =========================
  505.      *(This message will disappear, once this node revised.)*
  506.    Instead of giving the names of files or archive members on the
  507. command line, you can put the names into a file, and then use the
  508. `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'.
  509. Give the name of the file which contains the list of files to include
  510. as the argument to `--files-from'.  In the list, the file names should
  511. be separated by newlines.  You will frequently use this option when you
  512. have generated the list of files to archive with the `find' utility.
  513. `--files-from=FILE NAME'
  514. `-T FILE NAME'
  515.      Get names to extract or create from file FILE NAME.
  516.    If you give a single dash as a file name for `--files-from', (i.e.,
  517. you specify either `--files-from=-' or `-T -'), then the file names are
  518. read from standard input.
  519.    Unless you are running `tar' with `--create', you can not use both
  520. `--files-from=-' and `--file=-' (`-f -') in the same command.
  521.    The following example shows how to use `find' to generate a list of
  522. files smaller than 400K in length and put that list into a file called
  523. `small-files'.  You can then use the `-T' option to `tar' to specify
  524. the files from that file, `small-files', to create the archive
  525. `little.tgz'.  (The `-z' option to `tar' compresses the archive with
  526. `gzip'; *note gzip::. for more information.)
  527.      $ find . -size -400 -print > small-files
  528.      $ tar -c -v -z -T small-files -f little.tgz
  529. * Menu:
  530. * nul::
  531. File: tar.info,  Node: nul,  Prev: files,  Up: files
  532. `NUL' Terminated File Names
  533. ---------------------------
  534.    The `--null' option causes `--files-from=FILE-OF-NAMES' (`-T
  535. FILE-OF-NAMES') to read file names terminated by a `NUL' instead of a
  536. newline, so files whose names contain newlines can be archived using
  537. `--files-from'.
  538. `--null'
  539.      Only consider `NUL' terminated file names, instead of files that
  540.      terminate in a newline.
  541.    The `--null' option is just like the one in GNU `xargs' and `cpio',
  542. and is useful with the `-print0' predicate of GNU `find'.  In `tar',
  543. `--null' also causes `--directory=DIRECTORY' (`-C DIRECTORY') options
  544. to be treated as file names to archive, in case there are any files out
  545. there called `-C'.
  546.    This example shows how to use `find' to generate a list of files
  547. larger than 800K in length and put that list into a file called
  548. `long-files'.  The `-print0' option to `find' just just like `-print',
  549. except that it separates files with a `NUL' rather than with a newline.
  550. You can then run `tar' with both the `--null' and `-T' options to
  551. specify that `tar' get the files from that file, `long-files', to
  552. create the archive `big.tgz'.  The `--null' option to `tar' will cause
  553. `tar' to recognize the `NUL' separator between files.
  554.      $ find . -size +800 -print0 > long-files
  555.      $ tar -c -v --null --files-from=long-files --file=big.tar
  556. File: tar.info,  Node: exclude,  Next: Wildcards,  Prev: files,  Up: Choosing
  557. Excluding Some Files
  558. ====================
  559.      *(This message will disappear, once this node revised.)*
  560.    To avoid operating on files whose names match a particular pattern,
  561. use the `--exclude=PATTERN' or `--exclude-from=FILE-OF-PATTERNS' (`-X
  562. FILE-OF-PATTERNS') options.
  563. `--exclude=PATTERN'
  564.      Causes `tar' to ignore files that match the PATTERN.
  565.    The `--exclude=PATTERN' option will prevent any file or member which
  566. matches the shell wildcards (PATTERN) from being operated on (PATTERN
  567. can be a single file name or a more complex expression).  For example,
  568. if you want to create an archive with all the contents of `/tmp' except
  569. the file `/tmp/foo', you can use the command `tar --create
  570. --file=arch.tar --exclude=foo'.  You may give multiple `--exclude'
  571. options.
  572. `--exclude-from=FILE'
  573. `-X FILE'
  574.      Causes `tar' to ignore files that match the patterns listed in
  575.      FILE.
  576.    Use the `--exclude-from=FILE-OF-PATTERNS' option to read a list of
  577. shell wildcards, one per line, from FILE; `tar' will ignore files
  578. matching those regular expressions.  Thus if `tar' is called as
  579. `tar -c -X foo .' and the file `foo' contains a single line `*.o', no
  580. files whose names end in `.o' will be added to the archive.
  581. * Menu:
  582. * problems with exclude::
  583. File: tar.info,  Node: problems with exclude,  Prev: exclude,  Up: exclude
  584. Problems with Using the `exclude' Options
  585. -----------------------------------------
  586.    Some users find `exclude' options confusing.  Here are some common
  587. pitfalls:
  588.    * The main operating mode of `tar' will always act on file names
  589.      listed on the command line, no matter whether or not there is an
  590.      exclusion which would otherwise affect them.  In the example
  591.      above, if you create an archive and exclude files that end with
  592.      `*.o', but explicitly name the file `catc.o' after all the options
  593.      have been listed, `catc.o' *will* be included in the archive.
  594.    * You can sometimes confuse the meanings of `--exclude=PATTERN' and
  595.      `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS').  Be
  596.      careful: use `--exclude=PATTERN' when files to be excluded are
  597.      given as a pattern on the command line.  Use
  598.      `--exclude-from=FILE-OF-PATTERNS' to introduce the name of a file
  599.      which contains a list of patterns, one per line; each of these
  600.      patterns can exclude zero, one, or many files.
  601.    * When you use `--exclude=PATTERN', be sure to quote the PATTERN
  602.      parameter, so GNU `tar' sees wildcard characters like `*'.  If you
  603.      do not do this, the shell might expand the `*' itself using files
  604.      at hand, so `tar' might receive a list of files instead of one
  605.      pattern, or none at all, making the command somewhat illegal.
  606.      This might not correspond to what you want.
  607.      For example, write:
  608.           $ tar -c -f ARCHIVE.TAR -X '*/tmp/*' DIRECTORY
  609.      rather than:
  610.           $ tar -c -f ARCHIVE.TAR -X */tmp/* DIRECTORY
  611.    * You must use use shell syntax, or globbing, rather than `regexp'
  612.      syntax, when using exclude options in `tar'.  If you try to use
  613.      `regexp' syntax to describe files to be excluded, your command
  614.      might fail.
  615.    * In earlier versions of `tar', what is now the
  616.      `--exclude-from=FILE-OF-PATTERNS' option was called
  617.      `--exclude-PATTERN' instead.  Now, `--exclude=PATTERN' applies to
  618.      patterns listed on the command line and
  619.      `--exclude-from=FILE-OF-PATTERNS' applies to patterns listed in a
  620.      file.
  621. File: tar.info,  Node: Wildcards,  Next: after,  Prev: exclude,  Up: Choosing
  622. Wildcards Patterns and Matching
  623. ===============================
  624.    "Globbing" is the operation by which "wildcard" characters, `*' or
  625. `?' for example, are replaced and expanded into all existing files
  626. matching the given pattern.  However, `tar' often uses wildcard
  627. patterns for matching (or globbing) archive members instead of actual
  628. files in the filesystem.  Wildcard patterns are also used for verifying
  629. volume labels of `tar' archives.  This section has the purpose of
  630. explaining wildcard syntax for `tar'.
  631.    A PATTERN should be written according to shell syntax, using wildcard
  632. characters to effect globbing.  Most characters in the pattern stand
  633. for themselves in the matched string, and case is significant: `a' will
  634. match only `a', and not `A'.  The character `?' in the pattern matches
  635. any single character in the matched string.  The character `*' in the
  636. pattern matches zero, one, or more single characters in the matched
  637. string.  The character `\' says to take the following character of the
  638. pattern *literally*; it is useful when one needs to match the `?', `*',
  639. `[' or `\' characters, themselves.
  640.    The character `[', up to the matching `]', introduces a character
  641. class.  A "character class" is a list of acceptable characters for the
  642. next single character of the matched string.  For example, `[abcde]'
  643. would match any of the first five letters of the alphabet.  Note that
  644. within a character class, all of the "special characters" listed above
  645. other than `\' lose their special meaning; for example, `[-\\[*?]]'
  646. would match any of the characters, `-', `\', `[', `*', `?', or `]'.
  647. (Due to parsing constraints, the characters `-' and `]' must either
  648. come *first* or *last* in a character class.)
  649.    If the first character of the class after the opening `[' is `!' or
  650. `^', then the meaning of the class is reversed.  Rather than listing
  651. character to match, it lists those characters which are *forbidden* as
  652. the next single character of the matched string.
  653.    Other characters of the class stand for themselves.  The special
  654. construction `[A-E]', using an hyphen between two letters, is meant to
  655. represent all characters between A and E, inclusive.
  656.    Periods (`.') or forward slashes (`/') are not considered special
  657. for wildcard matches.  However, if a pattern completely matches a
  658. directory prefix of a matched string, then it matches the full matched
  659. string: excluding a directory also excludes all the files beneath it.
  660.    There are some discussions floating in the air and asking for
  661. modifications in the way GNU `tar' accomplishes wildcard matches.  We
  662. perceive any change of semantics in this area as a delicate thing to
  663. impose on GNU `tar' users.  On the other hand, the GNU project should be
  664. progressive enough to correct any ill design: compatibility at all price
  665. is not always a good attitude.  In conclusion, it is *possible* that
  666. slight amendments be later brought to the previous description.  Your
  667. opinions on the matter are welcome.
  668. File: tar.info,  Node: after,  Next: recurse,  Prev: Wildcards,  Up: Choosing
  669. Operating Only on New Files
  670. ===========================
  671.      *(This message will disappear, once this node revised.)*
  672.    The `--after-date=DATE' (`--newer=DATE', `-N DATE') option causes
  673. `tar' to only work on files whose modification or inode-changed times
  674. are newer than the DATE given.  If you use this option when creating or
  675. appending to an archive, the archive will only include new files.  If
  676. you use `--after-date' when extracting an archive, `tar' will only
  677. extract files newer than the DATE you specify.
  678.    If you only want `tar' to make the date comparison based on
  679. modification of the actual contents of the file (rather than inode
  680. changes), then use the `--newer-mtime=DATE' option.
  681.    You may use these options with any operation.  Note that these
  682. options differ from the `--update' (`-u') operation in that they allow
  683. you to specify a particular date against which `tar' can compare when
  684. deciding whether or not to archive the files.
  685. `--after-date=DATE'
  686. `--newer=DATE'
  687. `-N DATE'
  688.      Only store files newer than DATE.
  689.      Acts on files only if their modification or inode-changed times are
  690.      later than DATE.  Use in conjunction with any operation.
  691. `--newer-mtime=DATE'
  692.      Acts like `--after-date=DATE' (`--newer=DATE', `-N DATE'), but
  693.      only looks at modification times.
  694.    These options limit `tar' to only operating on files which have been
  695. modified after the date specified.  A file is considered to have
  696. changed if the contents have been modified, or if the owner,
  697. permissions, and so forth, have been changed.  (For more information on
  698. how to specify a date, see *Note Date input formats::; remember that the
  699. entire date argument must be quoted if it contains any spaces.)
  700.    Gurus would say that `--after-date=DATE' (`--newer=DATE', `-N DATE')
  701. tests both the `mtime' (time the contents of the file were last
  702. modified) and `ctime' (time the file's status was last changed: owner,
  703. permissions, etc) fields, while `--newer-mtime=DATE' tests only `mtime'
  704. field.
  705.    To be precise, `--after-date=DATE' (`--newer=DATE', `-N DATE')
  706. checks *both* `mtime' and `ctime' and processes the file if either one
  707. is more recent than DATE, while `--newer-mtime=DATE' only checks
  708. `mtime' and disregards `ctime'.  Neither uses `atime' (the last time the
  709. contents of the file were looked at).
  710.    Date specifiers can have embedded spaces.  Because of this, you may
  711. need to quote date arguments to keep the shell from parsing them as
  712. separate arguments.
  713.      *Please Note:* `--after-date=DATE' (`--newer=DATE', `-N DATE') and
  714.      `--newer-mtime=DATE' should not be used for incremental backups.
  715.      Some files (such as those in renamed directories) are not selected
  716.      properly by these options.  *Note incremental and
  717.      listed-incremental::.
  718.    To select files newer than the modification time of a file that
  719. already exists, you can use the `--reference' (`-r') option of GNU
  720. `date', available in GNU shell utilities 1.13 or later.  It returns the
  721. timestamp of that already existing file; this timestamp expands to
  722. become the referent date which `--newer' uses to determine which files
  723. to archive.  For example, you could say,
  724.      $ tar -cf ARCHIVE.TAR --newer="`date -r FILE`" /home
  725. which tells .
  726. File: tar.info,  Node: recurse,  Next: one,  Prev: after,  Up: Choosing
  727. Descending into Directories
  728. ===========================
  729.      *(This message will disappear, once this node revised.)*
  730.    Usually, `tar' will recursively explore all directories (either
  731. those given on the command line or through the
  732. `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option) for the
  733. various files they contain.  However, you may not always want `tar' to
  734. act this way.
  735.    The `--no-recursion' option inhibits `tar''s recursive descent into
  736. specified directories.  If you specify `--no-recursion', you can use
  737. the `find' utility for hunting through levels of directories to
  738. construct a list of file names which you could then pass to `tar'.
  739. `find' allows you to be more selective when choosing which files to
  740. archive; see *Note files:: for more information on using `find' with
  741. `tar', or look.
  742. `--no-recursion'
  743.      Prevents `tar' from recursively descending directories.
  744.    When you use `--no-recursion', GNU `tar' grabs directory entries
  745. themselves, but does not descend on them recursively.  Many people use
  746. `find' for locating files they want to back up, and since `tar'
  747. *usually* recursively descends on directories, they have to use the
  748. `! -d' option to `find'  as they usually do not want all the files in a
  749. directory.  They then use the {No Value For "op-file-from"} option to
  750. archive the files located via `find'.
  751.    The problem when restoring files archived in this manner is that the
  752. directories themselves are not in the archive; so the
  753. `--same-permissions' (`--preserve-permissions', `-p') option does not
  754. affect them--while users might really like it to.  Specifying
  755. `--no-recursion' is a way to tell `tar' to grab only the directory
  756. entries given to it, adding no new files on its own.
  757. File: tar.info,  Node: one,  Prev: recurse,  Up: Choosing
  758. Crossing Filesystem Boundaries
  759. ==============================
  760.      *(This message will disappear, once this node revised.)*
  761.    `tar' will normally automatically cross file system boundaries in
  762. order to archive files which are part of a directory tree.  You can
  763. change this behavior by running `tar' and specifying
  764. `--one-file-system' (`-l').  This option only affects files that are
  765. archived because they are in a directory that is being archived; `tar'
  766. will still archive files explicitly named on the command line or
  767. through `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), regardless
  768. of where they reside.
  769. `--one-file-system'
  770.      Prevents `tar' from crossing file system boundaries when
  771.      archiving.  Use in conjunction with any write operation.
  772.    The `--one-file-system' option causes `tar' to modify its normal
  773. behavior in archiving the contents of directories.  If a file in a
  774. directory is not on the same filesystem as the directory itself, then
  775. `tar' will not archive that file.  If the file is a directory itself,
  776. `tar' will not archive anything beneath it; in other words, `tar' will
  777. not cross mount points.
  778.    It is reported that using this option, the mount point is is
  779. archived, but nothing under it.
  780.    This option is useful for making full or incremental archival
  781. backups of a file system.  If this option is used in conjunction with
  782. `--verbose' (`-v'), files that are excluded are mentioned by name on the
  783. standard error.
  784. * Menu:
  785. * directory::                   Changing Directory
  786. * absolute::                    Absolute File Names
  787. File: tar.info,  Node: directory,  Next: absolute,  Prev: one,  Up: one
  788. Changing the Working Directory
  789. ------------------------------
  790.      *(This message will disappear, once this node revised.)*
  791.    To change the working directory in the middle of a list of file
  792. names, either on the command line or in a file specified using
  793. `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), use
  794. `--directory=DIRECTORY' (`-C DIRECTORY').  This will change the working
  795. directory to the directory DIRECTORY after that point in the list.
  796. `--directory=DIRECTORY'
  797. `-C DIRECTORY'
  798.      Changes the working directory in the middle of a command line.
  799.    For example,
  800.      $ tar -c -f jams.tar grape prune -C food cherry
  801. will place the files `grape' and `prune' from the current directory
  802. into the archive `jams.tar', followed by the file `cherry' from the
  803. directory `food'.  This option is especially useful when you have
  804. several widely separated files that you want to store in the same
  805. archive.
  806.    Note that the file `cherry' is recorded in the archive under the
  807. precise name `cherry', *not* `food/cherry'.  Thus, the archive will
  808. contain three files that all appear to have come from the same
  809. directory; if the archive is extracted with plain `tar --extract', all
  810. three files will be written in the current directory.
  811.    Contrast this with the command,
  812.      $ tar -c -f jams.tar grape prune -C food red/cherry
  813. which records the third file in the archive under the name `red/cherry'
  814. so that, if the archive is extracted using `tar --extract', the third
  815. file will be written in a subdirectory named `orange-colored'.
  816.    You can use the `--directory' option to make the archive independent
  817. of the original name of the directory holding the files.  The following
  818. command places the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a'
  819. into the archive `foo.tar':
  820.      $ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a
  821. However, the names of the archive members will be exactly what they were
  822. on the command line: `passwd', `hosts', and `libc.a'.  They will not
  823. appear to be related by file name to the original directories where
  824. those files were located.
  825.    Note that `--directory' options are interpreted consecutively.  If
  826. `--directory' specifies a relative file name, it is interpreted
  827. relative to the then current directory, which might not be the same as
  828. the original current working directory of `tar', due to a previous
  829. `--directory' option.
  830.    When using `--files-from' (*note files::.), you can put `-C' options
  831. in the file list.  Unfortunately, you cannot put `--directory' options
  832. in the file list.  (This interpretation can be disabled by using the
  833. `--null' option.)
  834. File: tar.info,  Node: absolute,  Prev: directory,  Up: one
  835. Absolute File Names
  836. -------------------
  837.      *(This message will disappear, once this node revised.)*
  838. `--absolute-names'
  839.      Do not strip leading slashes from file names.
  840.    By default, GNU `tar' drops a leading `/' on input or output.  This
  841. option turns off this behavior; it is equivalent to changing to the
  842. root directory before running `tar' (except it also turns off the usual
  843. warning message).
  844.    When `tar' extracts archive members from an archive, it strips any
  845. leading slashes (`/') from the member name.  This causes absolute
  846. member names in the archive to be treated as relative file names.  This
  847. allows you to have such members extracted wherever you want, instead of
  848. being restricted to extracting the member in the exact directory named
  849. in the archive.  For example, if the archive member has the name
  850. `/etc/passwd', `tar' will extract it as if the name were really
  851. `etc/passwd'.
  852.    Other `tar' programs do not do this.  As a result, if you create an
  853. archive whose member names start with a slash, they will be difficult
  854. for other people with a non-GNU `tar' program to use.  Therefore, GNU
  855. `tar' also strips leading slashes from member names when putting
  856. members into the archive.  For example, if you ask `tar' to add the
  857. file `/bin/ls' to an archive, it will do so, but the member name will
  858. be `bin/ls'.
  859.    If you use the `--absolute-names' (`-P') option, `tar' will do
  860. neither of these transformations.
  861.    To archive or extract files relative to the root directory, specify
  862. the `--absolute-names' (`-P') option.
  863.    Normally, `tar' acts on files relative to the working
  864. directory--ignoring superior directory names when archiving, and
  865. ignoring leading slashes when extracting.
  866.    When you specify `--absolute-names' (`-P'), `tar' stores file names
  867. including all superior directory names, and preserves leading slashes.
  868. If you only invoked `tar' from the root directory you would never need
  869. the `--absolute-names' (`-P') option, but using this option may be more
  870. convenient than switching to root.
  871. `--absolute-names'
  872.      Preserves full file names (inclusing superior dirctory names) when
  873.      archiving files.  Preserves leading slash when extracting files.
  874.    `tar' prints out a message about removing the `/' from file names.
  875. This message appears once per GNU `tar' invocation.  It represents
  876. something which ought to be told; ignoring what it means can cause very
  877. serious surprises, later.
  878.    Some people, nevertheless, do not want to see this message.  Wanting
  879. to play really dangerously, one may of course redirect `tar' standard
  880. error to the sink.  For example, under `sh':
  881.      $ tar -c -f archive.tar /home 2> /dev/null
  882. Another solution, both nicer and simpler, would be to change to the `/'
  883. directory first, and then avoid absolute notation.  For example:
  884.      $ (cd / && tar -c -f archive.tar home)
  885.      $ tar -c -f archive.tar -C  / home
  886.